/*!
 * \file worker_thread.hpp
 * \brief 线程池工作线程实现
 *
 * \details 工作线程实例附加到线程池，并执行该池的任务。
 *          
 *          工作线程是线程池的核心组件，负责：
 *          - 从线程池获取并执行任务
 *          - 管理线程生命周期
 *          - 处理异常和错误情况
 *          - 与线程池协调资源管理
 *          
 *          设计特点：
 *          - 基于RAII的资源管理
 *          - 异常安全的任务执行
 *          - 自动化的生命周期管理
 *          - 与线程池的松耦合设计
 *
 * Copyright (c) 2005-2007 Philipp Henkel
 *
 * Use, modification, and distribution are  subject to the
 * Boost Software License, Version 1.0. (See accompanying  file
 * LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
 *
 * http://threadpool.sourceforge.net
 *
 */

#ifndef THREADPOOL_DETAIL_WORKER_THREAD_HPP_INCLUDED
#define THREADPOOL_DETAIL_WORKER_THREAD_HPP_INCLUDED


#include "scope_guard.hpp"

#include <boost/smart_ptr.hpp>
#include <boost/thread.hpp>
#include <boost/thread/exceptions.hpp>
#include <boost/thread/mutex.hpp>
#include <boost/bind.hpp>


namespace boost { namespace threadpool { namespace detail 
{

  /*!
   * \brief 线程池工作线程类
   *
   * \details worker_thread代表一个执行线程。工作线程附加到线程池
   *          并处理该池的任务。工作线程及其内部boost::thread的
   *          生命周期会被自动管理。
   *
   *          核心功能：
   *          - 顺序执行线程池任务
   *          - 自动异常处理和恢复
   *          - 线程生命周期管理
   *          - 与线程池的双向通信
   *          - 优雅的关闭和清理
   *          
   *          这是一个辅助类，不能直接构造或访问。
   *          所有操作都通过线程池进行协调。
   *
   * \tparam Pool 线程池类型，工作线程将为其执行任务
   * 
   * \warning 此类不能直接构造或访问，仅供内部使用
   * 
   * \see pool_core
   */ 
  template <typename Pool>
  class worker_thread
  : public enable_shared_from_this< worker_thread<Pool> > 
  , private noncopyable
  {
  public:
    typedef Pool pool_type;         	   //!< 指示线程池的类型

  private:
    shared_ptr<pool_type>      m_pool;     //!< 指向创建此工作线程的线程池的指针
    shared_ptr<boost::thread>  m_thread;   //!< 指向执行运行循环的线程的指针

    
    /*!
     * \brief 构造新的工作线程
     * \param pool 指向其父线程池的指针
     * 
     * \details 私有构造函数，只能通过create_and_attach函数创建实例。
     *          这确保了工作线程的正确初始化和生命周期管理。
     * 
     * \see create_and_attach 函数
     */
    worker_thread(shared_ptr<pool_type> const & pool)
    : m_pool(pool)
    {
      assert(pool);
    }

	
	/*!
     * \brief 通知运行循环中发生异常
     * 
     * \details 当工作线程在执行任务时遇到未捕获的异常时调用。
     *          此函数会通知线程池该工作线程意外终止，
     *          线程池可以采取相应的恢复措施。
     */
	void died_unexpectedly()
	{
		m_pool->worker_died_unexpectedly(this->shared_from_this());
	}


  public:
	  /*!
       * \brief 顺序执行线程池的任务
       * 
       * \details 工作线程的主要执行循环。从线程池获取任务并顺序执行，
       *          直到线程池指示停止。这是工作线程的核心功能。
       *          
       *          执行流程：
       *          1. 设置异常保护机制
       *          2. 循环执行线程池分配的任务
       *          3. 正常结束时通知线程池
       *          4. 异常结束时触发异常处理
       *          
       *          异常安全：使用scope_guard确保即使发生异常
       *          也能正确通知线程池工作线程的状态变化。
       */
	  void run()
	  { 
		  scope_guard notify_exception(bind(&worker_thread::died_unexpectedly, this));

		  while(m_pool->execute_task()) {}

		  notify_exception.disable();
		  m_pool->worker_destructed(this->shared_from_this());
	  }


	  /*!
       * \brief 等待工作线程结束
       * 
       * \details 阻塞调用线程，直到此工作线程完全结束。
       *          这对于线程池的优雅关闭很重要，确保所有
       *          工作线程都正确终止后再清理资源。
       */
	  void join()
	  {
		  m_thread->join();
	  }


	  /*!
       * \brief 构造新的工作线程并将其附加到线程池
       * \param pool 指向线程池的指针
       * 
       * \details 静态工厂方法，用于创建和启动新的工作线程。
       *          这是创建工作线程的唯一正确方式。
       *          
       *          创建过程：
       *          1. 创建worker_thread实例
       *          2. 创建boost::thread并绑定run方法
       *          3. 线程自动开始执行
       *          
       *          线程安全：此方法是线程安全的，可以从
       *          多个线程同时调用以创建多个工作线程。
       */
	  static void create_and_attach(shared_ptr<pool_type> const & pool)
	  {
		  shared_ptr<worker_thread> worker(new worker_thread(pool));
		  if(worker)
		  {
			  worker->m_thread.reset(new boost::thread(bind(&worker_thread::run, worker)));
		  }
	  }

  };


} } } // namespace boost::threadpool::detail

#endif // THREADPOOL_DETAIL_WORKER_THREAD_HPP_INCLUDED

